Crate redis_async

source ·
Expand description

A client for Redis using Tokio and Futures.

Three interfaces are provided: one low-level, that makes no assumptions about how Redis is used; a high-level client, suitable for the vast majority of use-cases; a PUBSUB client specifically for Redis’s PUBSUB functionality.

§Low-level

client::connect returns a pair of Sink and Stream (see futures) which both transport resp::RespValues between client and Redis, these work independently of one another to allow pipelining. It is the responsibility of the caller to match responses to requests. It is also the responsibility of the client to convert application data into instances of resp::RespValue and back (there are conversion traits available for common examples).

This is a very low-level API compared to most Redis clients, but is done so intentionally, for two reasons: 1) it is the common demoniator between a functional Redis client (i.e. is able to support all types of requests, including those that block and have streaming responses), and 2) it results in clean Sinks and Streams which will be composable with other Tokio-based libraries.

For most practical purposes this low-level interface will not be used, the only exception possibly being the MONITOR command.

§High-level

client::paired_connect is used for most Redis commands (those for which one command returns one response, it’s not suitable for PUBSUB, MONITOR or other similar commands). It allows a Redis command to be sent and a Future returned for each command.

Commands will be sent in the order that send is called, regardless of how the future is realised. This is to allow us to take advantage of Redis’s features by implicitly pipelining commands where appropriate. One side-effect of this is that for many commands, e.g. SET we don’t need to realise the future at all, it can be assumed to be fire-and-forget; but, the final future of the final command does need to be realised (at least) to ensure that the correct behaviour is observed.

§PUBSUB

PUBSUB in Redis works differently. A connection will subscribe to one or more topics, then receive all messages that are published to that topic. As such the single-request/single-response model of paired_connect will not work. A specific client::pubsub_connect is provided for this purpose.

It returns a future which resolves to a PubsubConnection, this provides a subscribe function that takes a topic as a parameter and returns a future which, once the subscription is confirmed, resolves to a stream that contains all messages published to that topic.

Modules§

  • The client API itself.
  • Error handling
  • An implementation of the RESP protocol

Macros§

  • Macro to create a RESP array, useful for preparing commands to send. Elements can be any type, or a mixture of types, that satisfy Into<RespValue>.